Process Platform Model Plug-in

The Process Platform Model plug-in enables you to build transactional mobile applications over Process Platform Web services. It uses the cordys.ajax plug-in to invoke the services. This plug-in holds a collection of business objects along with their states and retrieves the collections of objects by executing the method with the specified namespace and parameters. The object and the attributes of the object are all Observable JSON Objects (using knockoutJS, which is added to your page automatically). These Observables can be bound to HTML or subscribed for changes. Any changes to the collection such as insert, update, or delete will be reflected in the HTML or notified to the subscribers.

The changes to the collection of objects can be sent to synchronize to the back-end using the APIs provided. This plug-in uses the Process Platform Tuple Protocol by default. The methods used for insert, update, or delete with the corresponding namespaces can be specified, if required.

The model will switch off the support (KnockoutJS will not be added to your page and no Observables will be created) if the model is read-only. You can use your own renderer in this case. Refer to the isReadOnly property under Properties for more details.

Settings

To use the plug-in in a new instance, it must be created in your Web page with the appropriate settings and must include method names and namespaces for the operations. The following properties can be passed as settings to the cordys.model plug-in while creating an instance:

Setting	Description	Default Value
objectName	Name of the objects in the structure received in the response, which will be a part of the model
isReadOnly	Option to specify if the model is read-only. It is automatically set to false if you specify at least one of the insert, update or delete settings. You can modify this behavior by specifying a value.	true
namespace	Namespace of the methods to be called by the model for read, update, insert, or delete operations. You can specify different values for different operations, if required.
useTupleProtocol	Boolean value that specifies if the model must use Tuple Protocol. You can set this to false if the Web service (method) used by the model does not use the Process Platform Tuple Protocol. If the value is set to true, then the model will use the Process Platform Tuple Protocol for all the insert, update, and delete operations.	true
read	Set of properties used in the read operation
create	Set of properties used in the create operation
update	Set of properties used in the update operation
delete	Set of properties used in the delete operation
defaults	Default set of parameters for the read, create, update, and delete methods
fields	Set of properties defining a template structure of the objects used in the model. For more information, refer to Fields Attribute on this page.

Note: Settings can be specified at various levels. If you want to set some of these settings so that they are applicable to all the instances in a page, you must set them for the $.cordys.model.defaults collection. Settings specific to a model can be set for the collection used in the creation of the model. This will override the values set for the $.cordys.model.defaults collection. You can also specify the settings when you call the read, create, update, and delete methods, which will again override the values set when you created the model.

Properties

Property	Value
<objectName>	KO Observable array consisting the collection of the Observable business objects. <objectName> refers to the name of your business object. Therefore, if your business object is called Order, then this will be myModel.Order. You can use this to call APIs of the Observable array such as destroy, which marks the object for deletion.

Methods

The following methods are supported by the cordys.model plug-in:

Method	Description
<objectName>()	Returns the array of Observable business objects
selectedItem()	Returns the current selected item in the model, if any; otherwise, returns null
selectedItem(businessObject)	Sets the current selected item in the model
create(options)	Creates all the newly inserted objects in the model using properties specified in the `create` property in the settings. Refer to the Properties for CRUD operations section for more details.
read(options)	Sends a request to retrieve the objects using properties specified in the `read` property in the settings. Refer to the Properties for CRUD operations section for more details.
update(options)	Updates all the modified objects in the model using the properties specified in the `update` property in the settings. Refer to the Properties for CRUD operations section for more details.
delete(options)	Deletes all deleted objects in the model using properties specified in the `delete` property in the settings. Refer to the Properties for CRUD operations section for more details.
synchronize(options)	Synchronizes all the inserted, updated, or deleted objects in the model to the back-end using properties specified in the `update` property
addBusinessObject(object)	Adds a new Object. It is wrapped into a KO Observable, which is returned. These are treated as new Objects and will be sent over in the next create or synchronize call for creation.
removeBusinessObject(object)	Marks the business object for deleting. These objects are sent over in the next create or synchronize call for deletion. All of the UIs that are bound to the business object will automatically hide the object. Such objects can be identified using the destroy flag on the object (with the Boolean value, true).
clear()	Clears the model of all the data
revert()	Reverts the model of any changes made that are not yet updated in the back-end. All the newly inserted objects are removed, all changed objects are reverted to their original state, and all the objects marked for deletion are cleared.
getNextPage(options)	Retrieves the next set of records in the cursor by sending a request. The options provided in the read setting of the model are used as a setting for the ajax call. You can also optionally override these by specifying them in the options passed here. For example, in the case where you want to invoke a different Web service
getPreviousPage(options)	Retrieves the previous set of records in the cursor by sending a request
hasNext()	Returns true if there are more objects in the cursor
hasPrevious()	Returns true if there are more objects in the cursor
putData(data)	Puts the given data into the model. It will search for all objects with a name equal to the objectName of the model, or put the data itself. Returns an array of the objects that are put.

Properties for CRUD operations

The following properties are an extension of the standard jQuery.ajax options:

Property

Description

method

Name of the method to be invoked

namespace

Namespace of the method to be invoked

parameters

Parameters of the method to be called, which can be one of the following:

An object with key or value pairs
An array of objects with name and value pairs. Each value can be either a string or a function returning a string.
A function returning an XML string
An XML string
Cursor: The cursor determines the size of the data set to return and the position to start from
Cursor takes the following properties:
- position: The start position of the data set to return results from. For example, when set to 5, the initial 5 results will be ignored.
- numRows: The number of rows to fetch from the data set. For example, when set to 5 only, 5 objects starting at position will be returned.
- maxRows: The maximum number of rows to expect will be ignored.
  Refer to Implementing Pagination for more information on using cursors.

Fields Attribute

The structure of the business objects is not always consistent. For example, empty fields may be excluded from the model or the child objects may have one or multiple instances. To specify additional (computed) fields, you can define the fields of the objects used in the model.
The fields attribute consists of an array of fields, which can be only the name of the field, or an object defining some additional properties.

The following properties are supported as a part of this attribute:

Property	Description
name	Name of the field in the object. If this property is unavailable, an empty field will be created in the object to avoid binding problems that may occur if the field does not exist in the object.
isArray	Boolean value to specify whether a child object can be handled always as an array
computed	Function, which returns the computed value of the field
path	Path expression to extract the field value from the data object
fields	Object defining the structure of a child object
persisted	Boolean value to specify if the field must be retained. The field is retained by default for all the types except for the computed field and the path expression.

Example for defining fields

empModel = new $.cordys.model({ objectName:"Employees", fields:[ "FirstName", "LastName", "Address", "BirthDate", "City", "Country", { name: "FullName", computed: function() { return this.FirstName() + " " + this.LastName() } }, { name: "Phone", path: "HomePhone", isArray: true, persisted: false } ] })

Authentication

The cordys.authentication plug-in handles the authentication for connecting to the Process Platform server. Refer to Authenticating Users with HTML5 SDK for more information.

Examples

For information on a list of employees and their details displayed using this plug-in, refer to Building Read-only Mobile Applications

Please refer to Building Transactional Mobile Applications for information on building transactional applications.

The following is the sample code snippet for creating a model for handling the employees from the Northwind database:

empModel = new $.cordys.model({ objectName: "Employees", defaults: { namespace: "http://schemas.cordys.com/NW", dataType: "json", method: "UpdateEmployees"  }, read: { method: "GetEmployeesObjects", parameters: { fromEmployeeID: "0", toEmployeeID: "99"  } } });

It is recommended to use jsrender and show read-only data in the cases where cursoring is not supported and where you expect medium to large data sets. The selected record or set of records can then be manipulated by setting it to a model.

pp108 : Process Platform Model Plug-in